package com.rois.librois.libRoISComp;

import com.rois.librois.RoIS.Argument;
import com.rois.librois.RoIS.Completed_Status;
import com.rois.librois.RoIS.ErrorType;
import com.rois.librois.RoIS.Parameter;
import com.rois.librois.RoIS.ParameterListHolder;
import com.rois.librois.RoIS.ResultListHolder;
import com.rois.librois.RoIS.ReturnCode_t;

import com.rois.librois.libRoISComp.MessageParameter;

/**
 * Interface definition for RoIS Component implementation.
 *
 * @author Miki Sato <miki.sato.1225@gmail.com>
 *
 *    The MIT licence
 *
 *    Copyright (C) 2011
 *      ATR Intelligent Robotics and Communication Laboratories, Japan
 *
 *    Permission is hereby granted, free of charge, to any person obtaining a copy
 *    of this software and associated documentation files (the "Software"), to deal
 *    in the Software without restriction, including without limitation the rights
 *    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 *    of the Software, and to permit persons to whom the Software is furnished to do so,
 *    subject to the following conditions:
 *
 *    The above copyright notice and this permission notice shall be included in all
 *    copies or substantial portions of the Software.
 *
 *    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 *    INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 *    PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 *    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 *    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 *    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

public interface ComponentEntity {
	/////////////////////////////////////////////////////////
	// Command Interface
	/////////////////////////////////////////////////////////
	/**
	 * receive a request to bind this component.
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t bind();

	/**
	 * receive a request to release this component.
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t release();

	/**
	 * receive a request to get parameter(s) of this component.
	 * @param parameters (out) list of parameter(s)
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t get_parameter(
		ParameterListHolder parameters
	);

	/**
	 * receive a request to set parameter(s) of this component.
	 * @param parameters list of parameter(s)
	 * @param command_id ID for this command message
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t set_parameter(
		Parameter[] parameters,
		org.omg.CORBA.StringHolder command_id
	);

	/**
	 * receive a request to execute a command message.
	 * @param command_type type of the command
	 * @param arguments argument parameter(s) for the command
	 * @param command_id ID for this command message
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t execute(
		String command_type,
		Argument[] arguments,
		org.omg.CORBA.StringHolder command_id
	);

	/////////////////////////////////////////////////////////
	// Query Interface
	/////////////////////////////////////////////////////////
	/**
	 * receive a request to query information in this component.
	 * @param query_type type of the query information
	 * @param condition condition for the query
	 * @param results (out) result parameter(s) for the query
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t query(
		String query_type,
		String condition,
		ResultListHolder results
	);

	/////////////////////////////////////////////////////////
	// Event Interface
	/////////////////////////////////////////////////////////
	/**
	 * receive a request to subscribe a event of this component.
	 * @param event_type type of the event
	 * @param condition condition for the event notification
	 * @param subscribe_id subscribe ID for the event
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t subscribe(
		String event_type,
		String condition,
		org.omg.CORBA.StringHolder subscribe_id
	);

	/**
	 * receive a request to cancel a event
	 * @param subscribe_id subscribe ID for the event
	 * @return RoIS::ReturnCode_t
	 */
	ReturnCode_t unsubscribe(
		String subscribe_id
	);

	/////////////////////////////////////////////////////////
	// System Interface
	/////////////////////////////////////////////////////////
	/**
	 * send "completed" message for a requested command message.
	 * @param command_id ID of the received command message
	 * @param status status of the command completion
	 * @param results result parameter(s) of the command execution
	 */
	void completed(
		String command_id,
		Completed_Status status,
		ResultListHolder results
	);

	/**
	 * send "receive_error" message.
	 * @param error_type type of the error
	 * @param results result parameter(s) of the error
	 */
	void receive_error(
			ErrorType error_type,
			ResultListHolder results
		);

	/**
	 * send "receive_event" message for a subscribed event.
	 * @param event_type type of the subscribed event
	 * @param subscribe_id ID of the subscribed event
	 * @param results result parameter(s) of the event
	 */
	void receive_event(
		String event_type,
		String subscribe_id,
		ResultListHolder results
	);

	/////////////////////////////////////////////////////////
	// For Access Component Data
	/////////////////////////////////////////////////////////
	/**
	 * get number of component parameters.
	 * @return number of parameters
	 */
	int get_event_prameter_size();

	/**
	 * get parameter for event notification.
	 * @param parameters (out) result parameter(s) for event message
	 */
	void get_event_parameters(
		MessageParameter[] parameters
	);

	/**
	 * get number of query parameters.
	 * @return number of parameters
	 */
	int get_query_prameter_size();

	/**
	 * get parameter for query.
	 * @param parameters (out) result parameter(s) for query message
	 */
	void get_query_parameters(
		MessageParameter[] parameters
	);
}
